Creating SAVE Files of Program Files

An IDL application created in IDL 6.0 or later can be saved in one or more SAVE files that will run in the IDL Virtual Machine. If an IDL application is to be run in the IDL Virtual Machine, it is not necessary to include an IDL distribution with the SAVE file because IDL Virtual Machine is installed on the user’s machine. The SAVE file need only include your own code, creating a smaller file that is easier to distribute.

To create SAVE files to run in the IDL Virtual Machine, do one of the following:

• Create SAVE files from one or more compiled .pro files with the SAVE procedure.
• Create SAVE files from a project by selecting Project > Build Project.

Creating SAVE files of object-oriented programs requires using RESOLVE_ALL with the CLASS keyword.

To enable your customers to run your application on a computer without IDL, you will need to include a runtime version of IDL in your application distribution.

Version Compatibility of SAVE Files

SAVE files created with a particular version of IDL are designed to be compatible with all later versions of IDL. However, SAVE files created with a later version of IDL may not be compatible with older versions of IDL. In other words, IDL SAVE files are "backwards" compatible, but not "forwards" compatible.

Each SAVE file contains a "revision level" which determines whether it can be restored by an older IDL version. If the revision level in the SAVE file is higher than the revision level for that version of IDL, then the file cannot be restored. The current revision levels are:

IDL Version	Save File Revision Level
5.0	1
5.1	5
5.3	6
5.6	7
6.0	8
6.1	9
8.0	10
8.2	11
8.3 or higher	12

Therefore, to distribute an application that can be used by users with different IDL versions, you should compile your code on the oldest IDL version that you want to support.

Note: The IDL Virtual Machine will execute IDL routines stored in SAVE files created with IDL version 6.0 and later. Any SAVE files created with previous versions of IDL must be recompiled using IDL 6.0 or later for them to run with the Virtual Machine.

Single vs. Multiple SAVE Files

There are several ways to include the necessary routines in your application:

• For a native IDL application, include all routines in the main SAVE file that is restored when your application is started. This makes all routines available without having to restore any additional SAVE files, and reduces the number of SAVE files used by your application. The easiest way to do this is to add all .pro files to a project, and build the project.
• Create a separate SAVE file containing all your routines. Use this method for a Callable application to keep certain routines separate from your main SAVE file in a native IDL application, or if your application includes routines provided to you as a SAVE file by another developer. To run any routines included in this SAVE file, you must restore the SAVE file by either calling a routine with the same name as the .sav file or restore it explicitly using RESTORE.
• Create a separate SAVE file for each routine used by your application. Assuming each .sav file uses the same name as the procedure or function it contains, this allows you to call each routine without having to explicitly restore its SAVE file because IDL will search the current directory and the defined !PATH for the .sav file and restore it automatically when it encounters the first call to the routine.

Examples

The following examples create SAVE files that are stand-alone IDL applications that can be run on any Windows, UNIX or macOS computer containing the IDL Virtual Machine or a licensed copy of IDL. See the following examples:

• Example: A SAVE File of a Simple Routine creates two SAVE files. One SAVE file contains variable data, the other SAVE file contains a procedure uses RESTORE to access the variable data in the first SAVE file.
• Example: A Save File of a Simple Widget Application displays an image in a simple widget application.
• Example: Creating a SAVE File of an Object Definition shows the special steps that must be taken when creating a SAVE file of an object that has dependencies upon other objects.
• Example: A SAVE File of a Custom iPlot Display restores variable data and plots it in an iPlot display.

Example: A SAVE File of a Simple Routine

The following example creates two SAVE files. One SAVE file contains variable data, loaded from an image file. This SAVE file is then restored by the program in the main SAVE file, which uses a simple call to the ARROW procedure to point out an area of interest within the image.

Save Image Variable Data

1. Start a fresh session of IDL. This avoids saving unwanted session information.

2. Read image data into a variable. Open an image file containing an MRI proton density scan of a human thorax, and read the data into a variable named image:

   READ_JPEG, (FILEPATH('pdthorax124.jpg', SUBDIRECTORY= $

       ['examples', 'data'])), image

3. Create a SAVE file containing the image data. Use the SAVE procedure to save the image variable in a SAVE file by entering the following:

   SAVE, image, FILENAME='imagefile.sav'

   This stores the SAVE file in your current working directory.

Note: When using the SAVE procedure, some users identify binary files containing variable data using a .dat extension instead of a .sav extension. While any extension can be used to identify files created with SAVE, it is recommended that you use the .sav extension to easily identify files that can be restored.

Save a Procedure that Restores Variable Data

1. Create the program file. Create the following IDL program that first restores the image variable contained within the imagefile.sav file. This variable is used in the following program statements defining the size of the window and in the TV routine which displays the image. The ARROW routine then draws an arrow within the window. Enter the following lines in a text editor.

   PRO draw_arrow

    

   ; Restore image data.

   RESTORE, 'imagefile.sav'

    

   ; Get the dimensions of the image file.

   s = SIZE(image, /DIMENSIONS)

    

   ; Prepare display device and display image.

   DEVICE, DECOMPOSED = 0

   WINDOW, 0, XSIZE=s[0], YSIZE=s[1], TITLE="Point of Interest"

   TV, image

    

   ; Draw the arrow.

   ARROW, 40, 20, 165, 115

    

   ; The IDL Virtual Manchine exits IDL when the end of a

   ; program is reached if there are not internal events. The

   ; WAIT statement here allows the user to view the .sav file

   ; results for 10 seconds when executed through the IDL

   ; Virtual Machine.

   WAIT, 10

    

   END

2. Save the file. Name the saved file draw_arrow.pro.

3. Reset the IDL session. Enter the following at the IDL prompt to ensure that no unwanted session information is saved along with the program:

   .FULL_RESET_SESSION

4. Compile the program. Enter the following at the IDL prompt:

   .COMPILE draw_arrow

5. Resolve dependencies. Use RESOLVE_ALL (or IRESOLVE if the routine has any dependencies on iTools components) to iteratively compile any uncompiled user-written or library procedures or functions that are called in any already-compiled procedure or function:

   RESOLVE_ALL

   Note: RESOLVE_ALL does not resolve procedures or functions that are called via quoted strings such as CALL_PROCEDURE, CALL_FUNCTION, or EXECUTE, or in keywords that can contain procedure names such as TICKFORMAT or EVENT_PRO. You must manually compile these routines.

6. Create the SAVE file. Create a file called draw_arrow.sav that contains the user-defined draw_arrow procedure. When the SAVEprocedure is called with the ROUTINES keyword and no arguments, it create a SAVE file containing all currently compiled routines. Because the procedures within the draw_arrow procedure are the only routines that are currently compiled in the IDL session, create the SAVE file as follows:

   SAVE, /ROUTINES, FILENAME='draw_arrow.sav'

   Note: When the name of the SAVE file uses the .sav extension and has the same base name as the main level program, it can be automatically compiled by IDL. This means that it can be called from another routine or restored from the IDL command line using only the name of the saved routine.

7. Test the SAVE file in the IDL Virtual Machine. Click on the splash screen and open draw_arrow.sav. You could also test the SAVE file from IDL, enter the following at the command prompt.

   RESTORE, 'draw_arrow.sav'

   draw_arrow

See Executing SAVE Files for all the available ways to run a SAVE file.

Example: A Save File of a Simple Widget Application

The following example creates a native IDL application that displays an image in a simple widget interface. When any application runs in the IDL Virtual Machine, there must some element (such as widget or interface events, or a WAIT statement) that keeps the application from immediately exiting with the END statement is reached. This example includes a Done button for this reason. The example in Example: A SAVE File of a Simple Routine includes a WAIT statement.

1. Create a .pro file. Enter the following in the IDL Editor, and save it as myApp.pro:

   PRO done_event, ev

   ; When the 'Done' button is pressed, exit

   ; the application.

    

   WIDGET_CONTROL, ev.TOP, /DESTROY

    

   END

    

   PRO myApp

    

   ; Read an image file.

   READ_JPEG, (FILEPATH('endocell.jpg', SUBDIRECTORY = $

      ['examples', 'data'])), image

    

   ; Find the dimensions of the image.

   info = SIZE(image,/DIMENSIONS)

   xdim = info[0]

   ydim = info[1]

    

   ; Create a base widget containing a draw widget

   ; and a 'Done' button.

   wBase = WIDGET_BASE(/COLUMN)

   wDraw = WIDGET_DRAW(wBase, XSIZE=xdim, YSIZE=ydim)

   wButton = WIDGET_BUTTON(wBase, VALUE='Done', EVENT_PRO='done_event')

    

   ; Realize the widgets.

   WIDGET_CONTROL, wBase, /REALIZE

    

   ; Retrieve the widget ID of the draw widget.

   WIDGET_CONTROL, wDraw, GET_VALUE=index

    

   ; Set the current drawable area to the draw widget.

   WSET, index

    

   ; Display some data.

   TV, image

    

   ; Call XMANAGER to manage the event loop.

   XMANAGER, 'myApp', wBase, /NO_BLOCK

    

   END

2. Reset the IDL session. Enter the following at the IDL prompt to ensure that no unwanted session information is saved along with the program:

   .FULL_RESET_SESSION

3. Compile the application. Select Run  > Compile to compile the .pro file.

4. Resolve dependencies. Type RESOLVE_ALL at the command line to resolve all procedures and functions that are called in the application:

   RESOLVE_ALL

   Note: If your program relies on iTools components, use IRESOLVE instead of RESOLVE_ALL.

5. Create the SAVE file. Enter the following to save the compiled application as a SAVE file:

   SAVE, /ROUTINES, FILENAME = 'myApp.sav'

See Executing SAVE Files for ways to run the SAVE file.

Example: Creating a SAVE File of an Object Definition

When you create a SAVE file that contains an object defined in a .pro file, you must save the .pro file as a SAVE file, just like any other procedure you wish to distribute. However, it is important to note that if the object has any inherited properties from superclasses or other objects, and the object definitions exist in .pro files, you must also compile and include these object definition files in your SAVE file. Objects using a .pro extension typically exist in the IDL distribution’s lib subdirectory and its subdirectories.

Note: Do not confuse the process of saving an instance of an object with saving its definition. A reference to an instantiated object is stored in an IDL variable, and must be saved in a SAVE file as a variable. An object definition, on the other hand, is an IDL routine, and must be saved in a SAVE file as a routine. It is important to remember that restoring an instance of an object does not restore the object’s definition. If the object is defined in .pro code, you must save the object definition routine and the object instance variable in separate SAVE files, and restore both instance and definition in the target IDL session.

The IDL distribution includes and example of a composite object composed of an image, a surface, and a contour, which are combined into a single object called the IDLexShow3 object. To see this object being used in an application, run the show3_track.pro file in the examples/doc/objects directory. This procedure has dependencies on two objects (trackball.pro and IDLexShow3__define.pro). You must use RESOLVE_ALL and explicitly include these two objects in the CLASS keyword string array in order to create a valid SAVE file.

If you fail to resolve all object dependencies, you will receive an error stating that there was an attempt to call and undefined procedure or function when you run the SAVE file. If the error references an object, add the object name to the CLASS keyword string array to resolve the problem. Undefined procedure or function errors are more likely to appear when you restore a SAVE file using the IDL Virtual Machine, which does not search !PATH to resolve routines. Using RESTORE at the command line does search !PATH. Therefore, a SAVE file that can be successfully executed using RESTORE may not succeed when called from the IDL Virtual Machine. If you are distributing SAVE files to users running the IDL Virtual Machine, make sure to test the SAVE file in the Virtual Machine.

Complete the following steps to create a save file of an object:

1. Reset your session. Either start a new IDL session or enter the following at the IDL prompt to ensure that no unwanted session information is saved along with the program:

   .FULL_RESET_SESSION

2. Open the main procedure. Open and compile show3_track.pro file by entering the following at the IDL command prompt:

   .COMPILE Show3_Track.pro

3. Resolve object dependencies. Use the CLASS keyword to resolve dependencies to other object .pro files by passing it a string or string array containing the name(s) of the objects:

   RESOLVE_ALL, CLASS=['Trackball', 'IDLexShow3']

4. Create the SAVE file. Enter the following at the IDL command prompt:

   SAVE, /ROUTINES, FILENAME='show3_track.sav'

5. Test the SAVE file. Select Start > Programs > IDL x.x > IDL Virtual Machine. Click on the splash screen and open show3_track.sav. You could also test the SAVE file from IDL. Enter the following at the command prompt.

   RESTORE, 'show3_track.sav'

   show3_track

See Executing SAVE Files for all the available ways to run a SAVE file.

Example: A SAVE File of a Custom iPlot Display

The following example configures a custom iPlot display and stores the program in a SAVE file. Restoring the SAVE file opens iPlot with the specified data.

When working with iTools, you can create an iTool State (.isv) file that contains data and application state information. You can share this file with other IDL users who have the same version or a newer version of IDL. See the iTool User’s Guide for details. This is not the same as packaging iTools functionality into a SAVE file, which is described in this example. When iTools functionality is packaged into a SAVE file, it can be accessed by IDL users or through the IDL Virtual Machine.

1. Access and save data. Save variable data from a batch file into a SAVE file:

   @plot01

   SAVE, FILENAME='plotdata01.sav'

2. Create the program file. This program restores data, and creates a plot display in an iPlot display. Enter the following lines in a text editor:

   PRO ex_saveiplot

    

   ; Define variables.

   RESTORE, 'plotdata01.sav'

    

   ; Use the LINFIT function to fit the data to a line:

   coeff = LINFIT(YEAR, SOCKEYE)

    

   ;YFIT is the fitted line:

   YFIT = coeff[0] + coeff[1]*YEAR

    

   ; Plot the original data points with PSYM = 4, for diamonds:

   iPLOT, YEAR, SOCKEYE, /YNOZERO, SYM_INDEX = 4, $

   SYM_COLOR=[255,0,0], LINESTYLE=6, $

   TITLE = 'Quadratic Fit', XTITLE = 'Year', $

   YTITLE = 'Sockeye Population'

    

   ; Overplot the smooth curve using a plain line:

   iPLOT, YEAR, YFIT, /OVERPLOT

    

   END

3. Reset your session. Enter the following at the IDL prompt to ensure that no unwanted session information is saved along with the program:

   .FULL_RESET_SESSION

4. Compile the program. Use the .COMPILE executive command as follows: Compile the main program file:

   .COMPILE ex_saveiplot

5. Resolve dependencies. Use IRESOLVE to resolve dependencies upon iTool components:

   IRESOLVE

6. Create the SAVE file. Use the /ROUTINES keyword to include all currently compiled routines:

   SAVE, /ROUTINES, FILENAME='ex_saveiplot.sav'

7. Test the SAVE file. Select Start > Programs > IDL x.x > IDL Virtual Machine. Click on the splash screen and open ex_saveiplot.sav. You could also run the SAVE file from IDL. Enter the following at the command prompt.

   RESTORE, 'ex_saveiplot.sav'

   ex_saveiplot

See Executing SAVE Files for all the available ways to run a SAVE file.

Other Examples of SAVE File Creation

See the following topics for additional SAVE file examples:

• ASCII_TEMPLATE contains Example: Create a SAVE File of a Custom ASCII Template
• XROI contains the following SAVE file examples:
• Example: Save ROI Data
• Example: Save the XROI Utility with ROI Data